Now that we’ve seen how to create a simple HTML report using R Markdown and display it online, let’s build upon those skills and see how to publish an electronic book (“e-book”) so that it can be shared with and viewed by others. To do so, we’ll make use of the {bookdown} package, which is what Mark uses for his lab guide. You can see many other examples of different books written with {bookdown} here.
Task: If you haven’t done so already, install the {bookdown} package. Load it when done.
## install bookdown if necessary
## install.packages("bookdown")
## load bookdown
library("bookdown")
Task: Navigate to GitHub and create a new
public repo called book-demo. Add a
README.md file and an R .gitignore file as
well (you can skip a license file). CLick the green Create
repository button when you’re ready.
Task: Click on the Settings button in the upper right.
Task: Click on the Pages button on the left side.
Task: Click on the None button under the Branch heading and swith it to main.
Task: Click on the / (root) button under the Branch heading and swith it to /docs.
Task: When you’re ready, click on the Save button.
Success: Your repo is now set to use GitHub Pages for displaying HTML files.
Task: Create a new project in RStudio from the
book-demo repo you just created.
Task: Create another project in RStudio but this time select the option for New Directory.
Task: From the Project Type window, select “Book project using bookdown”.
Task: Set the directory name and location to
anything you’d like (eg, tmp). This will be a temporary
folder/directory to hold a few files.
Task: Select bs4_book from the dropdown
menu for HTML book format.
Task: Check the box for “Open in a new session” and click the Create Project button.
Task: Navigate to the temporary
project/folder/directory you create above and move all
of the files except the .Rproj file to the
folder/directory where your book-demo project lives.
Success: You now have a template for creating and publishing an HTML e-book!
Task: Click on the Addins button at the top of your RStudio window and select “Preview Book” under “BOOKDOWN”.
Tip: You can also type
bookdown:::serve_book() at the command prompt to preview
your book.
Success: You can now see a preview of your book in the Viewer pane!
Now that we’ve pushed our basic HTML report to GitHub, we should be able to view it online.
Task: Navigate back your book-demo repo
on GitHub and you’ll see the /docs folder containing the
various HTML and other associated files.
Tip: Recall that GitHub cannot render HTML files in
a normal repo, but you can view your book by navigating to
https://USERNAME.github.io/book-demo/ where
USERNAME is your GitHub username.
Success: You now have an online book that you can update by making changes in your RStudio project and pushing them to GitHub.
Tip: You can add a link to your newly rendered document by edited the main page of your repo.
Task: Click on the small gear icon in the upper right, which will bring up a window to edit some aspects of your repo.
Task: In the Website field, type or
copy/paste the link to your rendered site, which should be
https://USERNAME.github.io/book-demo/ where
USERNAME is your GitHub username. Click on the green
Save changes button when you’re done.
Success: Your repo has now been updated to include a direct link to your properly rendered HTML report.